v2.1.1

Compare Source

Bug Fixes

• adapters/next/app: wrap optimistic search params update in startTransition (#​729) (01af1ea) - Thanks @​aryasaatvik !

v2.1.0

Compare Source

Bug Fixes

• Use optimistic search params in app router (#​718) (b5c0168), closes #​714 - Thanks @​aurorascharff !

Features

• Add parseAsISODate (#​707) (107fcc1) - Thanks @​tylersayshi !
• Add support for urlKeys in cache (#​725) (b8dcc6f), closes #​720 - Thanks @​anaclumos !
• Add urlKeys & clearOnDefault support for serializer (#​720) (c701afd), closes #​715 - Thanks @​blechatellier !
• Export OnUrlUpdateFunction type for Vitest v2 (#​712) (0645c51) - Thanks @​bryanjtc !
• Export the SearchParams type in both client & server bundles (#​710) (5a926f7)

v2.0.4

Compare Source

Bug Fixes

• Read queued updates when initialising state (#​703) (caa3779), closes #​702

v2.0.3

Compare Source

Bug Fixes

• Add stub CJS exports for old ESLint plugins (#​701) (464506b), closes #​691 - Thanks @​GBvanDam & @​acocheo !

v2.0.2

Compare Source

Bug Fixes

• Make clearOnDefault: true by default (#​700) (56c223f)

v2.0.1

Compare Source

Bug Fixes

• Add back the .js extension to the pages router adapter (#​694) (cd5bec1) - Thanks @​tiagoskaneta !
• Mark framework packages as optional peer dependencies (#​697) (df9e834) - Thanks @​nezouse !

v2.0.0

Compare Source

• Announcement post: https://nuqs.47ng.com/blog/nuqs-2
• Migrations docs: https://nuqs.47ng.com/docs/migrations/v2

Bug Fixes

• parseAsJson now requires a runtime validation function (53a37d4)

chore

• Drop mirrorring to next-usequerystate (4616a7b)
• ESM only (drop CJS support) (408fd38)
• Move urlKeys into the UseQueryStatesOptions type (8950bc8)
• Remove deprecated APIs (8d2ba24), closes #​425
• Rename nuqs/parsers to nuqs/server (b6bdc66)
• Update list of supported versions (9665a93)
• Update minimum supported Next.js version (c509a99), closes vercel/next.js#61419

Features

• Add adapter for One (a56aa11)
• Add custom adapters API (unstable) (3ef698f)
• Add React Router adapter (cb30a20)
• Add Remix adapter (4ae6c81)
• Add vanilla React adapter sandbox (e603a4d)
• Introducing adapters for other frameworks (a101370), closes #​603 #​620
• Provide specialised adapters for both Next.js routers (ac95384)
• Render pretty URLs in other adapters (6618f45)

BREAKING CHANGES

• Pass in a validation function like a Zod schema parse function
  to validate at runtime and infer the type of the returned data.
• UseQueryStatesOptions is now generic over the key map
  (the object containing parser definitions you pass to useQueryStates),
  and is now a type rather than an interface.
• When using Next.js, nuqs v2 requires next@>=14.2.0.
• nuqs now requires wrapping your app
  with a NuqsAdapter, which is a context provider connecting
  your framework APIs to the hooks' internals.
• The startTransition option no longer
  automatically sets shallow: false. The Options type
  is no longer generic.
• The "use client" directive was not included
  in the client import (import {} from 'nuqs'). It has now been added,
  meaning that server-side code needs to import from nuqs/server
  to avoid errors like:

Error: Attempted to call withDefault() from the server but withDefault is on
the client. It's not possible to invoke a client function from the server, it can
only be rendered as a Component or passed to props of a Client
Component.

• Drop support for [email protected]

Due to a bug in the implementation of shallow routing (WHS),
14.0.3 required a special case for syncing
against external navigation.

In [email protected], we're cleaning this up and requiring
a version of Next.js with bug-free support for
shallow routing (with or without experimental WHS
in 14.0.4, and with stabilised WHS in 14.0.5 onwards).

• export path has been renamed. Contents are identical.

Since the /parsers export contained the server cache,
this name makes better sense and helps outline the client/server
nature of features in nuqs.

• package is now only updating on the nuqs name.

The debugging printouts no longer check for next-usequerystate, only nuqs.

• the following deprecated APIs have been removed:

• queryTypes bag of parsers -> use individual parseAsXYZ parsers
  for better tree-shakeability.
• subscribeToQueryUpdates helper -> since Next.js 14.0.5,
  useSearchParams is reactive to shallow search params updates

• drop CJS support.

Since Next has ESM support since v12, it should not really be a breaking change for most.

Big thanks to @​andreisocaciu, @​tordans, @​prasannamestha, @​Talent30, @​neefrehman, @​chbg, @​dopry, @​weisisheng, @​hugotiger, @​iuriizaporozhets, @​rikbrown, @​mateogianolio, @​timheerwagen, @​psdmsft, and @​psdewar for helping !